Skip to content

Conversation

mwichmann
Copy link
Collaborator

@mwichmann mwichmann commented Jul 11, 2025

Reword AppendENVPath and PrependENVPath manpage entries.

Add more unit tests for the underlying functions, SCons.Util.AppendPath and SCons.Util.PrependPath (these changes are distinct from the ones in #4742 )

There are no changes to SCons itself.

Contributor Checklist:

  • I have created a new test or updated the unit tests to cover the new/changed functionality.
  • I have updated CHANGES.txt and RELEASE.txt (and read the README.rst).
  • I have updated the appropriate documentation

@mwichmann mwichmann added this to 4.10 Jul 11, 2025
@mwichmann mwichmann added documentation testsuite Things that only affect the SCons testing. Do not use just because a PR has tests. labels Jul 11, 2025
@mwichmann mwichmann moved this to In review in 4.10 Jul 11, 2025
<systemitem>os.path.normpath</systemitem>
and
<systemitem>os.path.normcase</systemitem>).
Append one or more path prefixes to an entry in a dictionary-valued
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

use "path" instead of "path prefixes"?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Path prefix is the "official" standardese term - as they're prepended, in order, to the thing you're looking for. POSIX:

PATH
This variable shall represent the sequence of path prefixes that certain functions and utilities apply in searching for an executable file known only by a filename. The prefixes shall be separated by a <colon> ( ':' ). When a non-zero-length prefix is applied to this filename, a <slash> shall be inserted between the prefix and the filename if the prefix did not end in <slash>. A zero-length prefix is a legacy feature that indicates the current working directory. It appears as two adjacent <colon> characters ( "::" ), as an initial <colon> preceding the rest of the list, or as a trailing <colon> following the rest of the list. A strictly conforming application shall use an actual pathname (such as .) to represent the current working directory in PATH. The list shall be searched from beginning to end, applying the filename to each prefix, until an executable file with the specified name and appropriate execution permissions is found. If the pathname being sought contains a <slash>, the search through the path prefixes shall not be performed. If the pathname begins with a <slash>, the specified path is resolved (see Pathname Resolution). If PATH is unset or is set to null, the path search is implementation-defined.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We've never used the term before in SCons docs.. we've used the term as a prefix to a path, but not as adding it to a list of paths to search.

IMHO they're a collection of paths to be searched..

Here's what we've used in SCons docs..

When called as a construction environment method, searches the paths in the path keyword argument, or if None (the default) the paths listed in the construction environment (env['ENV']['PATH']). The external environment's path list (os.environ['PATH']) is used as a fallback if the key env['ENV']['PATH'] does not exist.

I find "path prefixes" to be more confusing than just paths or path.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Obviously can change back, but I fail to see how it can be confusing. The passage you cite is different - it's "active" - when you call a function it's fine to say it "searches". The description of a variable is passive: it doesn't "search", just describes how it will be used at some later time.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One would not expect the author of text to find it confusing, but rather feed back from the consumers of such would be able to point it out.. ?

Reword AppendENVPath and PrependENVPath manpage entries.

Add more unit tests for the underlying functions,
SCons.Util.AppendPath and SCons.Util.PrependPath

Signed-off-by: Mats Wichmann <[email protected]>
Signed-off-by: Mats Wichmann <[email protected]>
Just wordsmithing, no meaning changes.

Signed-off-by: Mats Wichmann <[email protected]>
@bdbaddog
Copy link
Contributor

I like the improved wording! Thanks for your patience in getting to this.
Note there was duplicate entries at line 171 in CHANGES.txt, I've fixed and pushed. (removing the version with misspellings).

@bdbaddog bdbaddog merged commit 01c9257 into SCons:master Aug 17, 2025
@github-project-automation github-project-automation bot moved this from In review to Done in 4.10 Aug 17, 2025
@mwichmann mwichmann added this to the NextRelease milestone Aug 17, 2025
@mwichmann mwichmann deleted the tweak/ENVPath branch August 17, 2025 13:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation testsuite Things that only affect the SCons testing. Do not use just because a PR has tests.
Projects
Status: Done
Development

Successfully merging this pull request may close these issues.

2 participants